home *** CD-ROM | disk | FTP | other *** search
/ Amiga Magazin: Amiga-CD 1997 May & June / Amiga-CD 1997 #5-6.iso / grafik / wildfire / wildfirefpu / doc / yafa-doc.txt < prev    next >
Text File  |  1997-03-07  |  10KB  |  249 lines
  1.  
  2.                           Y A F A
  3.                 An IFF Format For Animations
  4.  
  5.                   Release V1.0 (26-May-96)
  6.  
  7.  
  8. Introduction
  9. ----------------------------------------------------------------------------
  10.   The animation file format YAFA provides features not seen in other
  11.   formats, and its main advantage is the great number of different ways
  12.   to store the animation frames.
  13.  
  14.   Here is a list of the main features:
  15.    -bit depth 1...8 (2...256 colors, HAM6 and HAM8)
  16.    -planar or chunky frames
  17.    -optional timecode-per-frame
  18.    -optional palette-per-frame
  19.    -optional delta-compression (similar to IFF ANIM)
  20.    -optional XPK-compression
  21.    -annotations
  22.  
  23.   Using the compression options it is possible to optimize a YAFA file
  24.   for maximum playback speed or minimum storage size. Chunky frame data
  25.   usually compresses better and can be displayed directly on gfx boards.
  26.  
  27.  
  28. Description
  29. ----------------------------------------------------------------------------
  30.   YAFA files are made of chunks just like specified in the IFF standard.
  31.   In the text below the special chunks defined for YAFA and their structure
  32.   are explained. Please note that there may very well be some extensions
  33.   in the future. If you are interested in including your own ideas in YAFA
  34.   please let us know.
  35.   (things to think about: depth>8, other (better) compression ...)
  36.  
  37.  
  38.  
  39.      FORM YAFA
  40.      .INFO        general information
  41.      .DRGB        palette (useless with palette-per-frame)
  42.      .DLTX        delta expansion (useless without delta compression)
  43.      .PROF        frame offsets (useless without any compression)
  44.      .TTBL        timecodes for each frame (used if present)
  45.      .ANNO        annotation
  46.      .BODY        frames (and palette-per-frame)
  47.  
  48.   The order of the chunks is not important except that the BODY chunk must
  49.   be the last chunk in the file.
  50.   Chunks that are useless in a special file should be omitted.
  51.  
  52.  
  53.  
  54.   INFO
  55.   ----
  56.  
  57.   This chunk is mandatory for YAFA files. It contains data about the frames
  58.   and specifies which optional features are used.
  59.  
  60.    UWORD width       (in pixels - must be a multiple of 16)
  61.    UWORD height      (in pixels)
  62.    UWORD depth       (currently supported: 1...8)
  63.    UWORD speed       (playback speed, each anim frame is displayed this number
  64.                       of video frames, frames-per-second can be calculated by
  65.                       dividing video-frames-per-second (ie. PAL: 50) by speed)
  66.    UWORD frames      (number of frames)
  67.    UWORD frametype   (currently supported are:
  68.                       0 planar
  69.                       1 planar with XPK compression
  70.                       3 chunky 8bit with XPK compression
  71.                       4 chunky 8bit
  72.    UWORD flags       (set bits have following meanings:
  73.                       BIT 0 Hold-And-Modify mode (HAM)
  74.                       BIT 1 palette-per-frame ('dynamic palette')
  75.                       BIT 2 delta compression, the next two bits specify
  76.                             the type:
  77.                                       BIT 4 set - LONG
  78.                                       else BIT 3 set - WORD
  79.                                       else BYTE
  80.                      other bits are unused, clear them for future compatibility)
  81.  
  82.  
  83.   DRGB
  84.   ----
  85.  
  86.   This chunk contains the palette used for all frames. It can be omitted when
  87.   dynamic palette is enabled.
  88.   The palette is stored in a loadrgb structure which can be used as a parameter
  89.   for graphics/LoadRGB32() for instance.
  90.   
  91.   struct loadrgb
  92.   {
  93.   UWORD count;     (number of colors)
  94.   UWORD first;     (number of the color register to receive the first color
  95.                     in this structure)
  96.   ULONG colors []; (array of color values, each color value consists of three
  97.                     longwords containing the Red, Green and Blue components in
  98.                     their highest bytes)
  99.   };
  100.   
  101.  
  102.  
  103.   DLTX
  104.   ----
  105.  
  106.   This chunk is only useful in files with delta-compressed frames. It contains
  107.   ULONG dltx that is the number of bytes by which the largest
  108.   delta-compressed  frame is larger than a uncompressed frame. If there is
  109.   no delta frame larger than an uncompressed frame then dltx is NULL.
  110.   Also if the frames are delta-compressed and the DLTX chunk is missing
  111.   the value for dltx should be considered as NULL.
  112.   This value is needed for allocating memory for frame buffers, you have to
  113.   take (uncompressed size + dltx) bytes.
  114.  
  115.  
  116.  
  117.   PROF
  118.   ----
  119.  
  120.   This chunk contains an array of ULONG values that are the offsets of each
  121.   frame's end from the beginning of the BODY. In YAFA files without compression
  122.   all frames have the same size and the offsets can easily be calculated when
  123.   they are needed, the PROF is obsolete in this case.
  124.   If you need to know the size of a specific frame (ie. for loading) simply
  125.   calculate: size=PROF[i]-PROF[i-1]. (i = 1...number_of_frames-1)
  126.   If you need to seek to a specific frame (ie. when skipping some frames) get
  127.   the offset from the beginning of the BODY out of the PROF: offset=PROF[i-1].
  128.   For the first frame you have to use: size=PROF[0] and offset=0.
  129.  
  130.  
  131.  
  132.   TTBL
  133.   ----
  134.  
  135.   This chunk contains an array of UWORDs that are the speed values for each
  136.   individual frame. There is no explicit way to enable these timecodes, if
  137.   the chunk is present in a YAFA file it is used. Anyway, the global speed
  138.   in the INFO chunk is not obsolete, it must always be set to a legal value
  139.   (>0). In the TTBL values of 0 are allowed, they just mean not to take
  140.   a new speed but to use the one from the previous frame instead.
  141.   So you might want to add a TTBL chunk to all YAFA anims you create. If they
  142.   are not needed currently they can all be set to 0, so they have no effect
  143.   at all, but they can be edited later.
  144.  
  145.  
  146.  
  147.   ANNO
  148.   ----
  149.  
  150.   This chunk contains some additional information included by the creator
  151.   of the YAFA file. In order to allow the content to have an odd length and
  152.   to be able to extract exactly this odd length from the ANNO, there is
  153.   an ULONG value at the beginning of the chunk containing the real length
  154.   of the content. Behind the content there is a pad byte if needed to make
  155.   the chunk length even.
  156.   The content itself should be a printable zero-terminated ASCII-string. This
  157.   leaves the possibility to include binary files too, you just have to make
  158.   sure that there is a NULL byte in front of the binary stuff.
  159.  
  160.  
  161.  
  162.   BODY
  163.   ----
  164.  
  165.   This chunk contains the frames one after another. It is not structured,
  166.   which means that you need the information stored in the other chunks to know
  167.   how to deal with the BODY chunk.
  168.  
  169.   *planar:
  170.    simply raw bitplanes
  171.  
  172.   *chunky:
  173.    one byte represents one pixel, the value is the color number,
  174.    valid for depth = 5...8 (unused bits are cleared ofcourse)
  175.  
  176.   *XPK compression:
  177.    every frame is compressed individually,
  178.    use xpkmaster.library's functions: XpkPack(), XpkUnPack()
  179.  
  180.   *Delta compression:
  181.    The delta compression used in YAFA is similar to the one in IFF ANIM7, but
  182.    in YAFA files the first two frames are uncompressed. Compressed frames
  183.    look like this:
  184.     -8 pointers to opcode lists
  185.     -8 pointers to data lists
  186.     -opcode lists (elements are bytes)
  187.     -data lists (elements are bytes/words/longwords)
  188.    Unused pointers are set to NULL. (De-)Compression is performed on a
  189.    bitplane-by-bitplane basis. The bitplane is splitted into vertical columns
  190.    that are 8/16/32 pixels wide. (for byte/word/long compression)
  191.    The opcode lists consist of opcodes for every column. A column starts with
  192.    an opcode count. If the opcode count is zero it means that the complete
  193.    column remains unchanged. The opcodes are of three classes and refer to a
  194.    varying amount of data (to fetch from the corresponding data list) depending
  195.    on the class:
  196.     -skip op (non-zero, hi bit clear): skip this number of rows in the
  197.      destination bitplane
  198.     -uniq op (non-zero, hi bit set): clear hi bit, the remainder is the
  199.      number of data items to copy (each item to the next destination row)
  200.     -same op (zero): followed by a count byte, that says how many destination
  201.      rows are to be set to the same data item (the next item in the data list)
  202.   
  203.   *combinations:
  204.    All combinations of the above mentioned features are possible. When chunky
  205.    data is to be delta-compressed it is treated like it was planar with eight
  206.    bitplanes.
  207.    When reading a YAFA file do following steps (if necessary):
  208.      -read frame (using PROF for size and offset)
  209.      -XpkUnpack()
  210.      -delta-decompress
  211.      -chunky to planar
  212.    When writing a YAFA file do the analogous steps in reverse order.
  213.  
  214.   *dynamic palette:
  215.    colors are stored directly behind the frame they belong to in a loadrgb
  216.    structure (see DRGB chunk),
  217.    in case of XPK compression frame data and palette are compressed together,
  218.    you have to get the uncompressed size from XPK in order to be able to
  219.    calculate the start of the palette:
  220.               palette_pt = frame_pt + size - colorsize
  221.          with  colorsize = number_of_colors * 12 + 4
  222.  
  223.  
  224. Contact
  225. ----------------------------------------------------------------------------
  226.  
  227.   The YAFA animation format is developed by WK-Artworks and Infect.
  228.   We are also programming our own player and processor/converter using
  229.   YAFA which are already available (ie. on Aminet). In order to make YAFA
  230.   more popular we ask programmers of image/animation software to support
  231.   this new format in their programs.
  232.   If you have any questions and/or suggestions you are welcome to contact:
  233.  
  234.  
  235.    Michael Henke (aka Smack/Infect)
  236.    Praetoriusstr. 1/205
  237.    06124 Halle/Saale
  238.    Germany
  239.    EMail: epgbd@cluster1.urz.uni-halle.de
  240.  
  241.    or
  242.  
  243.    Andreas Maschke (aka WK-Artworks)
  244.    Zenkerstraße 5
  245.    06108 Halle/Saale
  246.    Germany
  247.    Phone: ++49 (0)345/5170331
  248.    EMail: epgbc@cluster1.urz.uni-halle.de
  249.